 /*******************************************************************************
  * Copyright (c) 2005, 2006 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.ui.dialogs;

 import org.eclipse.core.runtime.IAdaptable;
 import org.eclipse.jface.preference.IPreferencePage;
 import org.eclipse.jface.preference.PreferenceDialog;
 import org.eclipse.jface.preference.PreferenceManager;
 import org.eclipse.jface.preference.PreferencePage;
 import org.eclipse.swt.widgets.Shell;
 import org.eclipse.ui.internal.dialogs.FilteredPreferenceDialog;
 import org.eclipse.ui.internal.dialogs.PropertyDialog;
 import org.eclipse.ui.internal.dialogs.WorkbenchPreferenceDialog;

 /**
  * The PreferencesUtil class is the class that opens a properties or preference
  * dialog on a set of ids.
  * @since 3.1
  */
 public final class PreferencesUtil {

     /**
      * Apply the data to the first page if there is any.
      * @param data The data to be applied
      * @param displayedIds The ids to filter to.
      * @param dialog The dialog to apply to.
      */
     private static void applyOptions(Object data, String [] displayedIds,
             FilteredPreferenceDialog dialog) {
         if (data != null) {
             dialog.setPageData(data);
             IPreferencePage page = dialog.getCurrentPage();
             if (page instanceof PreferencePage) {
                 ((PreferencePage) page).applyData(data);
             }
         }

         if (displayedIds != null) {
             dialog.showOnly(displayedIds);
         }
     }

     /**
      * Creates a workbench preference dialog and selects particular preference page.
      * If there is already a preference dialog open this dialog is used and its
      * selection is set to the page with id preferencePageId.
      * Show the other pages as filtered results using whatever filtering
      * criteria the search uses. It is the responsibility of the caller to then
      * call <code>open()</code>. The call to <code>open()</code> will not
      * return until the dialog closes, so this is the last chance to manipulate
      * the dialog.
      *
      * @param shell
      * The Shell to parent the dialog off of if it is not
      * already created. May be <code>null</code>
      * in which case the active workbench window will be used
      * if available.
      * @param preferencePageId
      * The identifier of the preference page to open; may be
      * <code>null</code>. If it is <code>null</code>, then the
      * preference page is not selected or modified in any way.
      * @param displayedIds
      * The ids of the other pages to be displayed using the same
      * filtering criterea as search. If this is <code>null</code>,
      * then the all preference pages are shown.
      * @param data
      * Data that will be passed to all of the preference pages to be
      * applied as specified within the page as they are created. If
      * the data is <code>null</code> nothing will be called.
      *
      * @return a preference dialog.
      * @since 3.1
      * @see PreferenceDialog#PreferenceDialog(Shell, PreferenceManager)
      */
     public static final PreferenceDialog createPreferenceDialogOn(Shell shell,
             String preferencePageId, String [] displayedIds, Object data) {
         FilteredPreferenceDialog dialog = WorkbenchPreferenceDialog.createDialogOn(shell,
                 preferencePageId);

         applyOptions(data, displayedIds, dialog);

         return dialog;
     }

     /**
      * Creates a workbench preference dialog to a particular preference page.
      * Show the other pages as filtered results using whatever filtering
      * criteria the search uses. It is the responsibility of the caller to then
      * call <code>open()</code>. The call to <code>open()</code> will not
      * return until the dialog closes, so this is the last chance to manipulate
      * the dialog.
      *
      * @param shell
      * The shell to use to parent the dialog if required.
      * @param propertyPageId
      * The identifier of the preference page to open; may be
      * <code>null</code>. If it is <code>null</code>, then the
      * dialog is opened with no selected page.
      * @param element
      * IAdaptable An adaptable element to open the dialog
      * on.
      * @param displayedIds
      * The ids of the other pages to be displayed using the same
      * filtering criterea as search. If this is <code>null</code>,
      * then the all preference pages are shown.
      * @param data
      * Data that will be passed to all of the preference pages to be
      * applied as specified within the page as they are created. If
      * the data is <code>null</code> nothing will be called.
      *
      * @return A preference dialog showing properties for the selection or
      * <code>null</code> if it could not be created.
      * @since 3.1
      */
     public static final PreferenceDialog createPropertyDialogOn(Shell shell,
             final IAdaptable element, String propertyPageId, String [] displayedIds, Object data) {

         FilteredPreferenceDialog dialog = PropertyDialog.createDialogOn(shell, propertyPageId,
                 element);

         if (dialog == null) {
             return null;
         }

         applyOptions(data, displayedIds, dialog);

         return dialog;

     }

 }

